home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Reference / DevCon / Milan_1991 / Devcon91.2 / Arexx / simplerexx / SimpleRexx.prt < prev    next >
Encoding:
Text File  |  1992-09-01  |  7.8 KB  |  173 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                                      SimpleRexx
  8.  
  9.                    A Simplified Interface into the world of ARexx
  10.  
  11.  
  12.           ARexx,  ARexx,  ARexx.    2.0  has  ARexx.   So, why and how do I
  13.           support ARexx?
  14.  
  15.           The "Why?" has been answered elsewhere and that is not  what this
  16.           article is  about.   Let it suffice that you should support ARexx
  17.           within your application.  It  is  a  standard  that  Commodore is
  18.           pushing and  we hope  that all  new applications  will have ARexx
  19.           support.
  20.  
  21.           As to the "How?",  that  is  what  this  article  is  about.   We
  22.           understand that  your existing software may not currently support
  23.           ARexx and that some of you may never even have looked at  what is
  24.           needed to  support ARexx.   New applications can be designed with
  25.           ARexx support in mind  and, with  the advent  of the  AppShell by
  26.           David Junod,  the work  involved to support ARexx is nothing more
  27.           than  what  is  needed  to  support   the  features   within  you
  28.           application.    However,  existing  code  may  not  move into the
  29.           AppShell to  easily and  you may  wish to  do a  minor upgrade to
  30.           your application to support ARexx.
  31.  
  32.           SimpleRexx is  a set  of routines that handle the low-level ARexx
  33.           work for you in such a way as to have your application  work with
  34.           or without ARexx on the target system.  The goal of SimpleRexx is
  35.           to make adding at least the minimum level of ARexx  support to an
  36.           application a trivial task.
  37.  
  38.  
  39.                                  Working with ARexx
  40.  
  41.           REXX  is,  at  its  heart,  a  string  processing language.  Most
  42.           everything that happens in REXX is in the form of  a string; even
  43.           numbers are passed as ASCII representations in most situations.
  44.  
  45.           The Amiga  implementation of REXX, known as ARexx, and is part of
  46.           Release  2.0  of  AmigaDOS.      ARexx   has   a   very  complete
  47.           implementation of  the REXX language plus the ability to send and
  48.           receive control messages from "outside" sources.   ARexx  the can
  49.           operate  on  them  in  synchronous fashion.  The messages contain
  50.           text strings that are then interpreted by ARexx  as REXX commands
  51.           or by the "outside" source (the Application) as its commands.
  52.  
  53.           An application  that "supports ARexx" is one that can receive and
  54.           send ARexx messages.  The messages  are, like  the REXX language,
  55.           string  based  and  contain  the  command string of the operation
  56.           wanted.
  57.  
  58.           To make this even more interesting,  there are  ways to  send and
  59.           receive data from ARexx.  The data can come in the message itself
  60.           or via the ARexx RVI (Rexx Variable Interface).   In  either case
  61.  
  62.  
  63.  
  64.  
  65.  
  66.           data  can  be  transferred  to  and from ARexx.  A complete ARexx
  67.           supporting application would need to be  able to  send data  to a
  68.           requesting ARexx program/script and get data from that program.
  69.  
  70.           The following  code shows how to use the ARexx support library to
  71.           send and receive ARexx messages.  It also  is a  "wrapper" around
  72.           these  functions  to  provide  a simplified interface to ARexx to
  73.           help promote  and simplify  the idea  of adding  ARexx support to
  74.           your existing applications.
  75.  
  76.           SimpleRexxExample.c is  a very  simple example  of the use of the
  77.           calls in SimpleRexx.  The test.rexx  script is  an example script
  78.           to try  running while SimpleRexxExample is running.  It will send
  79.           commands  to   SimpleRexxExample   in   order   to   control  it.
  80.           test.results is the output of test.rexx.
  81.  
  82.  
  83.                                 Overview of Functions
  84.  
  85.           The source  to SimpleRexx  is a single file.  It is SimpleRexx.c.
  86.           The  header  file  to  that  contains  the  type  definitions and
  87.           prototypes for the functions is in the file SimpleRexx.h.
  88.  
  89.           Functions  that  are  "available"  via  SimpleRexx  are  used  as
  90.           follows:
  91.  
  92.  
  93.                rexx_handle=InitARexx(AppBaseName,Extension)
  94.  
  95.                     This initializes a SimpleRexx context.  The rexx_handle
  96.                     is much  like a  file handle in that it will be used in
  97.                     all  other  calls  that  make  use  of  this SimpleRexx
  98.                     context.    Since  all SimpleRexx calls correctly check
  99.                     the rexx_handle before doing work, you  do not  need to
  100.                     check the  return result of this call.  If ARexx is not
  101.                     available on your system,  SimpleRexx will  just not do
  102.                     anything.
  103.  
  104.  
  105.                port_name=ARexxName(rexx_handle)
  106.  
  107.                     This  function  returns  a  pointer  to the name of the
  108.                     ARexx port for your context.  The name is based  on the
  109.                     AppBaseName  plus   an  invocation   number  such  that
  110.                     multiple copies of an application can  run at  the same
  111.                     time.  If you have no ARexx port, it returns NULL.
  112.  
  113.  
  114.                sigmask=ARexxSignal(rexx_handle)
  115.  
  116.                     This  function  returns  the  signal  bit  mask that is
  117.                     needed for the port that is part of your context.  This
  118.                     should be  combined with  other signal masks to produce
  119.                     the argument to the Wait() call.  This  returns NULL if
  120.  
  121.  
  122.  
  123.  
  124.  
  125.                     there is no signal mask.
  126.  
  127.  
  128.                rmsg=GetARexxMsg(rexx_handle)
  129.  
  130.                     This  function  returns  the  next Rexx message that is
  131.                     waiting.  rmsg==NULL if there is no message or ARexx is
  132.                     not around.   rmsg==REXX_RETURN_ERROR if a message sent
  133.                     to ARexx via SendARexxMsg() returns an error.
  134.  
  135.  
  136.                ReplyARexxMsg(rexx_handle,rmsg,result,error)
  137.  
  138.                     This function  replies  the  ARexx  message  gotten via
  139.                     GetARexxMsg().   The "result"  is a pointer to a result
  140.                     string that is  returned  via  OPTIONS  RESULTS  in the
  141.                     RESULT ARexx variable.  If you have no result, set this
  142.                     to NULL.  Error is the error severity  level.   If this
  143.                     is 0,  the result  string will  be returned, if this is
  144.                     non-zero, the error level will be returned in RC.
  145.  
  146.  
  147.                worked=SendARexxMsg(rexx_handle,string,StringFileFlag)
  148.  
  149.                     This function sends the string to  ARexx.   It sets the
  150.                     default host  to the  context and  sets the RXFB_STRING
  151.                     bit in the  message  if  the  "StringFileFlag"  is set.
  152.                     This routine  returns FALSE if the message was not sent
  153.                     for some reason.
  154.  
  155.  
  156.                worked=SetARexxLastError(rexx_handle,rmsg,ErrorString)
  157.  
  158.                     This function uses the RVI (Rexx Variable Interface) to
  159.                     set  a  variable  named  <AppBaseName>.LASTERROR to the
  160.                     ErrorString.  This is where the  "error" message should
  161.                     go if  there is  an error.  This function returns FALSE
  162.                     if this fails for any reason.
  163.  
  164.  
  165.                FreeARexx(rexx_handle)
  166.  
  167.                     This closes a SimpleRexx  context.   The rexx_handle is
  168.                     one that  was gotten  from InitARexx().  The routine is
  169.                     fully error checked so that you can pass it a  NULL and
  170.                     it  will  do  nothing.    This is useful if you want to
  171.                     just blindly use the rexx_handle.
  172.  
  173.